Summary

Implements stateless resume for tempo/session.

A client can reuse an existing Tempo payment channel without persisting local session runtime state, as long as either:

• the client already knows a channelId, or
• the server can resolve the authenticated payer identity and discover a reusable channel for that payer.

The implementation adds server-side reusable-channel discovery, client-side session hydration from challenge hints, zero-dollar proof bootstrap in SessionManager, and receipt reconciliation that keeps server accounting authoritative without letting server hints inflate the next signed voucher.

What This PR Implements

• server-side reusable channel discovery keyed by payer + payee + token + escrow contract + chain
• tempo.session({ resolveSource }) so an application can supply the authenticated payer identity from its own auth/session layer
• session challenge hints in request.methodDetails: channelId, acceptedCumulative, requiredCumulative, spent, and deposit
• client-side hydration of session state from server hints, with on-chain recovery as the fallback when only channelId is known
• bounded zero-dollar proof bootstrap in SessionManager so a stateless client can authenticate first, receive a session challenge, and then resume or open a channel
• Payment-Receipt and SSE reconciliation that updates local accounting state while preserving the client’s own signing boundary
• deterministic precedence for explicit channelId, which remains the direct reuse path when the client already has it

End-to-End Flow

sequenceDiagram
    participant Client
    participant Server
    participant Auth as Zero-dollar proof auth
    participant Session as Session challenge
    participant Store as Channel store
    participant Chain as On-chain channel

    Client->>Server: GET /resource
    alt auth required and no local session runtime
        Server-->>Client: 402 + tempo.charge(amount=0)
        Client->>Auth: sign proof credential
        Client->>Server: retry with proof credential
    end

    Server->>Store: resolve payer and discover reusable channel
    Server-->>Client: 402 + tempo.session challenge

    alt explicit or discovered reusable channel available
        Server-->>Client: channelId + accepted/spent/deposit/required hints
        Client->>Session: hydrate local runtime state from hints
    else channelId known but no server snapshot
        Client->>Chain: recover channel state on-chain
        Chain-->>Client: settled amount + deposit
    else no reusable channel
        Client->>Chain: open new channel
    end

    Client->>Server: retry with open/voucher credential
    Server-->>Client: 200 + Payment-Receipt(channelId, acceptedCumulative, spent)
    Client->>Session: reconcile receipt into local accounting state

Server Behavior

When the server receives a tempo/session request, it can now attach reusable-channel hints to the session challenge.

If request.channelId is present, that channel is treated as the requested reuse target. The server verifies that the stored channel matches the request dimensions and, when valid, returns challenge hints for that channel.

If request.channelId is absent and resolveSource() returns a payer DID such as did:pkh:eip155:<chainId>:<address>, the server:

• parses the authenticated payer address from the DID
• looks up channels owned by that payer
• filters candidates to the same recipient, token, escrow contract, and chain
• excludes channels that are finalized, closing, zero-deposit, or unable to satisfy the next request amount
• selects a deterministic best candidate, preferring the newest viable channel and then stronger voucher progress as a tiebreaker

The backing ChannelStore gains payer-indexed lookup to support this discovery efficiently.

Client Behavior

The client now distinguishes between:

• server-reported accounting state: acceptedCumulative, spent, deposit
• client-authorized signing state: cumulativeAmount

This distinction is the core of the reconciliation model.

Server hints and receipts can raise the client’s view of accepted/spent/deposit, but they do not directly increase the next signed voucher amount. The next voucher is still derived from the client’s locally authorized cumulative amount plus the current request or stream increment.

This allows the client to resume from server knowledge, process receipts, and handle SSE top-ups without trusting the server to choose a larger authorization boundary than the client intended to sign.

SessionManager now owns a bounded retry loop for this flow:

1. perform the original request
2. if challenged for zero-dollar auth, create a proof credential and retry
3. read the returned session challenge
4. hydrate or recover the target channel
5. create the session credential and retry
6. reconcile the resulting receipt into runtime state

API and Plumbing Changes

• tempo.session() server request hooks now receive the incoming HTTP Request so resolveSource() can inspect application auth context
• Fetch.from() invokes method response hooks for successful retry responses so session receipt reconciliation also works through the generic client path
• tempo/session request parsing accepts additive session hint fields and carries them through methodDetails

Compatibility

• all new session hint fields are additive and optional
• explicit channelId reuse continues to work as the direct fast path
• resolveSource is optional; when absent, the flow still supports explicit channelId reuse and opening new channels
• clients that do not use the new hint fields continue to operate with the existing open/retry behavior